Skip to content

Add effect/chat, @effect/chat-slack, @effect/chat-discord and @effect/chat-whatsapp - #10581

Open
tim-smart wants to merge 89 commits into
mainfrom
effect-chat
Open

tim-smart wants to merge 89 commits into
mainfrom
effect-chat

Conversation

@tim-smart

@tim-smart tim-smart commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Adds effect/chat: a platform-neutral model and router for chat bots

Slack signature verification

Slack webhook and interactivity layers now require a caller-provided Mac service. Provide a runtime layer such as NodeCrypto.layerMac, or Mac.layerWebCrypto with SecureRandom.layerWebCrypto. Invalid key configuration is a build defect; verification errors and malformed signatures return 401. The five-minute timestamp rule is unchanged.

Janitor dogfood (EFF-3766 / EFF-3791) must provide a Mac layer when upgrading its snapshot; that migration is outside this change.

WhatsApp

@effect/chat-whatsapp is a Cloud API adapter for one business phone number. Groups are reserved ({phoneNumberId}/g/...) and refused for now. WhatsApp has no edit, so ChatMarkdown now posts each streamed part once, when it is final, on any adapter without edit. The webhook delivers at least once: a click can run twice, and WhatsAppChat.deliveryKey is there for handlers that must claim it first.

Live checks on Graph API v23.0, from a Meta test number to one phone (the default baseUrl is v24.0): Meta counts text bodies, interactive bodies, reply button and list row titles, and row ids in code points, which the adapter's UTF-16 count never undercounts (captions, the list button and section titles were not measured), and reply button ids in UTF-8 bytes up to 256, which the adapter now checks before the call. Formatting, .md uploads as text/plain, media headers beside buttons and the BSUID grammar behave as intended. Meta gave up on a webhook response after about 22 s, so the default deadline is now 10 s. One short burst was accepted above the pair rate, which is not a sustained rate, so minWriteInterval stays at 6 s. A user can tap several reply buttons or pick one row twice, and each tap is its own click. layer takes an optional messagingAccountId, sent as Meta's documented messaging_account_id to say which Messaging account sends when the token can use more than one. Meta documents it as optional now, required for such tokens on the newest Graph version from H1 2027 and on every version from H1 2028.

Still unchecked: whether error 131047 comes back on the send or as a status, BSUID sends from a production number, sends from a production number with Messaging accounts and a payment method (with and without messagingAccountId), and groups.

Validated with root lint, typecheck (tsrs and tsc) and JSDoc checks, plus the chat suites including WhatsApp (557 passed, 94 opt-in live tests skipped).

Microsoft Teams

@effect/chat-teams is a Bot Framework Connector adapter for one Entra tenant. It is private, and stays private until every release check in its README has tenant evidence. Nothing in it has run against a tenant, the default capabilities included.

  • On by default, unverified: post, edit, delete, getThread and getUser (which needs in).
  • Implemented, off by default: buttons, dialogs with field errors, agent commands with private answers, startThread and download, each behind an unverified option.
  • Not implemented in this version: Graph reads (fetchMessage, history, opener), replyTo, files, native streams and selects. They are Unsupported.

Inbound requests need a Bot Framework RS256 token with a msteams-endorsed key, the app as audience, and a serviceurl matching the activity, from the configured tenant. Anything else gets 403. The OpenID metadata and key set are fetched with redirects off, and the metadata is read up to 64 KiB. The bot token goes only to allowlisted Connector hosts and never to a redirect host. Button and dialog tokens are signed, not encrypted, and button tokens have no replay protection. A dialog token binds the exact conversation id of the click, so a submit keeps the click's thread. The element caps are the adapter's own and count the whole signed token, so a dialog's definition counts against modalMetadataLength too. The text form escapes $ outside code.

Core changes: Jwks.makeRemote takes a filter for raw keys (applied after the maxKeys count), and the ChatAdapter docs say how an adapter derives messageLength from a fixed overhead reservation and sets its own element caps.

The README lists the 18 release checks and which capability each gates. They need a Microsoft 365 developer tenant, an Azure Bot resource and a public tunnel. Validated locally with root lint, tsrs typecheck and JSDoc checks, the Teams suites (73 tests, including the conformance suite over a stubbed Connector, the webhook over signed tokens and the dialog invokes) and the Jwks tests.

Interaction cancellation

ChatInteraction.handle now registers cancellation cleanup atomically with handler startup and protects the deadline handoff. Late clicks still run detached; late submits and commands still return without waiting for cleanup. One scheduler-budget regression reproduces the original orphaned-handler race. Root lint and tsrs typecheck pass; the core and four adapter chat suites pass (622 tests, 94 opt-in live tests skipped).

Closes EFF-3824
Closes EFF-3822
Closes EFF-3823

CI repair

Narrow the Teams webhook test JSON before accessing its dialog payload so the full Deno workspace check passes. Give the full Node test job an explicit 4 GiB old-space budget after two runs exhausted the default roughly 2 GiB heap. This is a capacity mitigation, not evidence of a flaky test or a proven memory-leak fix; the full CI rerun must confirm it. Full local Deno checking, root lint/typecheck, 303 core-chat/Teams tests, and all 14,198 core tests pass (58 core tests skipped). No published API changes.

Slack test stabilization

Use the test clock for modal validation and API error mapping, leaving explicit late-click/late-submit coverage and production deadlines unchanged. The interactions suite passed 10 consecutive runs each on Bun 1.4.2 and Node 26.13.0 (11 tests per run). Root lint and typecheck pass. This test-only follow-up requires no changeset.

Closes EFF-3828

@changeset-bot

changeset-bot Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 7ad4fee

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 39 packages
Name Type
effect Patch
@effect/chat-slack Patch
@effect/chat-discord Patch
@effect/chat-whatsapp Patch
@effect/chat-telegram Patch
@effect/opentelemetry Patch
@effect/vitest Patch
@effect/ai-amazon-bedrock Patch
@effect/ai-anthropic Patch
@effect/ai-cloudflare Patch
@effect/ai-openai-compat Patch
@effect/ai-openai Patch
@effect/ai-openrouter Patch
@effect/ai-typesafe Patch
@effect/atom-react Patch
@effect/atom-solid Patch
@effect/atom-vue Patch
@effect/platform-browser Patch
@effect/platform-bun Patch
@effect/platform-cloudflare Patch
@effect/platform-deno Patch
@effect/platform-node-shared Patch
@effect/platform-node Patch
@effect/sql-clickhouse Patch
@effect/sql-d1 Patch
@effect/sql-libsql Patch
@effect/sql-mssql Patch
@effect/sql-mysql2 Patch
@effect/sql-pg Patch
@effect/sql-pglite Patch
@effect/sql-sqlite-bun Patch
@effect/sql-sqlite-do Patch
@effect/sql-sqlite-node Patch
@effect/sql-sqlite-react-native Patch
@effect/sql-sqlite-wasm Patch
@effect/docgen Patch
@effect/doctest Patch
@effect/graphql-generator Patch
@effect/openapi-generator Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@effect-janitor effect-janitor Bot added the 4.0 label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name Current Size Previous Size Difference
arbitrary-combinators.ts 40.09 KB 40.09 KB 0.00 KB (0.00%)
basic.ts 7.31 KB 7.31 KB 0.00 KB (0.00%)
batching.ts 11.21 KB 11.21 KB 0.00 KB (0.00%)
brand.ts 7.00 KB 7.00 KB 0.00 KB (0.00%)
cache.ts 11.73 KB 11.73 KB 0.00 KB (0.00%)
config.ts 23.09 KB 23.09 KB 0.00 KB (0.00%)
differ.ts 22.20 KB 22.20 KB 0.00 KB (0.00%)
http-client.ts 27.45 KB 27.45 KB 0.00 KB (0.00%)
http-router.ts 37.59 KB 37.59 KB 0.00 KB (0.00%)
logger.ts 12.19 KB 12.19 KB 0.00 KB (0.00%)
metric.ts 9.65 KB 9.65 KB 0.00 KB (0.00%)
optic.ts 7.21 KB 7.21 KB 0.00 KB (0.00%)
pubsub.ts 16.21 KB 16.21 KB 0.00 KB (0.00%)
queue.ts 13.09 KB 13.09 KB 0.00 KB (0.00%)
schedule.ts 11.99 KB 11.99 KB 0.00 KB (0.00%)
schema-bigdecimal.ts 14.29 KB 14.29 KB 0.00 KB (0.00%)
schema-binary.ts 42.48 KB 42.48 KB 0.00 KB (0.00%)
schema-class.ts 21.96 KB 21.96 KB 0.00 KB (0.00%)
schema-codegen.ts 30.70 KB 30.70 KB 0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts 30.56 KB 30.56 KB 0.00 KB (0.00%)
schema-representation-roundtrip.ts 28.26 KB 28.26 KB 0.00 KB (0.00%)
schema-string-transformation.ts 15.54 KB 15.54 KB 0.00 KB (0.00%)
schema-string.ts 12.50 KB 12.50 KB 0.00 KB (0.00%)
schema-template-literal.ts 16.43 KB 16.43 KB 0.00 KB (0.00%)
schema-toArbitrary.ts 39.63 KB 39.63 KB 0.00 KB (0.00%)
schema-toCodecJson.ts 21.11 KB 21.11 KB 0.00 KB (0.00%)
schema-toEquivalence.ts 21.28 KB 21.28 KB 0.00 KB (0.00%)
schema-toFormatter.ts 21.37 KB 21.37 KB 0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts 26.42 KB 26.42 KB 0.00 KB (0.00%)
schema-toRepresentation.ts 21.45 KB 21.45 KB 0.00 KB (0.00%)
schema.ts 21.05 KB 21.05 KB 0.00 KB (0.00%)
stm.ts 14.46 KB 14.46 KB 0.00 KB (0.00%)
stream.ts 10.56 KB 10.56 KB 0.00 KB (0.00%)

tim-smart added a commit to Effect-TS/janitor that referenced this pull request Nov 13, 2026
…ixes

Moves every Effect package to the eeccfc1 snapshot of Effect-TS/effect#10581.
ChatMarkdown now posts the overflow of a reply whose files are refused as
text, in the code fence it was cut in, and @effect/chat-slack's webhook
deadline covers reading the body. Janitor's workarounds for both come out;
their regression tests stay and run against the library.
tim-smart added a commit to Effect-TS/janitor that referenced this pull request Nov 13, 2026
Moves Janitor's Slack and Discord chat onto effect/chat, @effect/chat-slack
and @effect/chat-discord from the eeccfc1 snapshot of Effect-TS/effect#10581.

Closes EFF-3766
Comment thread .changeset/effect-chat.md Resolved
Adds effect/chat/ChatMarkdown (post and stream over post-then-edit and
NativeStream), the Descriptor measure contract from EFF-3689, and a native
stream in the ChatTest fake with its conformance rules.
- Record a created message before onPart and before an interrupt can land,
  and make appends uninterruptible with their bookkeeping, so the finalizer
  never posts or appends the same text twice.
- Keep files and trailing blank text with the last part after a cut, and
  send files with the overflow file.
- Repair a native stream by edit with the whole known text, the retried
  chunk included, without waiting for more input.
- Reserve room in a native stream to close the open code fence, and close
  it before a rollover or an age rotation.
- Retry without files only for reasons a file refusal can give.
- Run posts, starts and appends in a fiber of their own that commits its
  answer. An interrupt waits for it within the finish timeout, and only the
  timeout cuts it off, recording its text as uncertain.
- Record a pending stop, rollover or repair in the reply state, so the
  finalizer resumes it after an interrupt. A stop cut off is sent again.
- Add TooLarge.subject so an adapter can say the files were too large.
  The unattachedNote fallback retries a TooLarge only for subject files,
  and a text refusal fails the reply as settled in EFF-3689.
Write fibers now live in a scope owned by the reply rather than the loop,
and a failed upstream ends the loop at once. The finish timeout then starts
while the write is still in flight: its answer is kept if it arrives in
time, and its text is reported as uncertain if the timeout cuts it off.
The upstream-failure race could cut off the stop that follows a denied
append. The reply had already failed, so the finish was skipped and the
native stream stayed open. The finish now runs for a pending stop or write
in that case too, sending only the stop, within the finish timeout, and
keeping the Chat error the reply failed with.
A user asking the bot to stop working in a thread, as Slack's stop button
does. Its dedupe key is stop/{thread}/{id}, where id is the platform's id
for the request (Slack's event_ts).
The Slack adapter for effect/chat: the Events API webhook, the pure
normaliser, every adapter op over a minimal Web API client, native
streaming with the agent session status and the stop button, and the
Slack emoji table generated from iamcal/emoji-data v16.0.0.
After a 429 on a stream append or an edit, the next write to that message
waits for the retry-after, and later writes to it wait twice the interval.
- Leave Slack's emoji-as-shortcode limit to Slack. The preflight counted
  `<` as four characters and refused text Slack accepts.
- A failed files.info after the share is an uncertain post (Unknown),
  never a refusal or a retryable error.
- The webhook deadline covers the bot user lookup.
- Mentions come only from the rich_text block's real elements. Tokens are
  aligned with the block's items, and text never adds a mention.
- A 429's doubled interval carries over a stream rotation to the reply's
  next part.
- Edits to one message are at least 3 seconds apart, the spec's starting
  number.
- NativeStream.start takes `continues`, the message id of the reply's
  previous part. ChatMarkdown passes it for every part after the first.
  The Slack adapter keys its 429 backoff by message and shares it with a
  stream started with `continues`, so the backoff follows its reply and
  never passes to another reply in the thread. A stop with end "done"
  drops it.
- Each attempt of a paced write reads the pace afresh, so an edit retried
  after a 429 keeps the doubled interval.
- Mention alignment marks the no-tokens-left state impossible while a real
  item remains, and reconstruction can't step past the tokens. Text with
  fewer tokens than real items no longer hangs.
- Remove the unused blocksLength and blocksCost exports from length.ts.
Thirteen cases, 24 deliveries, captured by janitor production's EFF-3709
fixture capture from chat-testing-123. Bodies are the delivered strings,
minus the envelope token the capture drops and with avatar and file URLs
replaced. No signature was logged. events.test.ts runs every delivery
through the webhook, signed with a test secret, and checks what it
normalises to.

All were posted by the bot, so Slack sent no app_mention: the read-back
pair tests are now labelled as reconstructed.
Tim typed the H1 to H9 cases and clicked Stop in chat-testing-123 while
janitor production's EFF-3709 capture logged the deliveries. Thirteen new
cases, 54 of the 100 deliveries; the rest are janitor's status messages
for later cases. Bodies are verbatim apart from the envelope token and
avatar and file URLs. No delivery carried a retry header.

events.test.ts now checks six independently delivered message and
app_mention pairs normalise to the same event, that edits (including
the app_mention Slack sends when an edit adds a mention) give nothing,
reactions with a tone and a custom emoji, and the stop button.

The stops show only the first click in a thread names the open stream,
so StopRequested's docs no longer say an empty messageIds means no
stream was open. With no stream, Slack sends streaming_message_ts: [];
the recorded G2 event only lacked it because that log dropped it.
A Discord adapter for effect/chat on dfx: gateway dispatch with the
channel type lookup, the pure normalize, threads, reactions, history with
the thread opener, post-then-edit streaming, and recorded fixtures.
Item 11 of the fixture list, read back through REST: the gateway
recorder had stopped before they were sent.
An opener the bot may not read (Forbidden) is treated like a deleted one:
history starts at the first reply and opener is None. A message whose
timestamp doesn't parse fails decoding instead of throwing from normalize,
and an unparseable timestamp in a post answer or thread metadata no
longer throws.
chat.postMessage and chat.update now go as blocks: [markdown] plus a text the adapter builds, with every <, > and & as an entity and allowed tokens intact, cut to 16,000 code points on a post and 3,800 UTF-8 bytes on an update. The bot's own messages read back with text rendered from their rich_text blocks. A two-tone emoji name no longer resolves.
…fallback

- Text elements escape Markdown syntax when rendered, and code spans keep
  a space at each end.
- A one-tone name resolves to the same tone twice where upstream keys an
  emoji only by two tones.
- The generated mention test only exempts tokens the current notify allows.
- Document why a lone hair component costs 4.
ChatMarkdown.stream fell back to post-then-edit whenever there was no native
stream, so on an adapter without edit the first edit failed and left a
truncated reply. It now buffers each part and posts it once, at a rollover or
at the end. ChatHandler and ChatInteraction no longer promise that the
platform never delivers an accepted event or an interaction again.
A platform with short button labels, such as WhatsApp's 20, refused the rule's name as a label.
One adapter per business phone number: posts with one Graph send, reply buttons, link buttons and lists, one file per post, the Meta webhook with signature checks and ordered dispatch, delivery and update keys, templates and read receipts. Groups are reserved and refused.
@tim-smart tim-smart changed the title Add effect/chat, @effect/chat-slack and @effect/chat-discord Add effect/chat, @effect/chat-slack, @effect/chat-discord and @effect/chat-whatsapp Nov 15, 2026
A private @effect/chat-teams over the Bot Framework Connector, with capabilities that no tenant has confirmed behind unverified options. Jwks.makeRemote gains a filter for raw keys, and the ChatAdapter docs say how adapters derive messageLength and their own element caps.
Report a changed BSUID that has no sender, answer the webhook deadline without waiting for finalizers, keep a modal refusal from delaying a click, map a refused upload to file_refused, and keep shortcut references, multi-line definitions and container-nested fences as typed.
Fork the webhook worker under a mask so a cancellation always interrupts it, match a nested fence's closer inside the opener's quotes and list items, and end a kept definition or table at the start of a block.
A tab only partly taken by a list item's indentation left the rest looking like a closing fence, so the code after it was rendered.
The indented-code guard checked the line as typed, so a quoted or listed code line with tab indentation fell through to inline rendering. It now checks what is left inside the containers, with tabs expanded, and still emits the line as typed.
Close the escape bypasses a GFM parse found: backticks in link titles,
indented fences, emphasis runs past the nesting limit, tables ended by
another block, and backslashes inside bare URLs. Check the rendered
output with micromark's GFM parser, a test-only dependency.

Take an anonymous admin's command principal from sender_chat, and give
an animation one attachment. Test the README's secret-header redaction
and the durable-acceptance recipe, and document the click and command
deadlines and the release status.
… tests

- Emphasis: every delimiter run that could open counts toward the depth
  limit and closers are never subtracted; the limit accounts for the
  deepest container in the paragraph, so lazy continuation lines and
  intraword underscores cannot exceed 16 levels.
- Tables keep their pipes only when neither row is indented and the
  header follows a blank line, a heading or the start of the text, so
  footnote text is no longer read as a table.
- A setext `=` is kept only under plain top-level paragraph lines.
- assertInert enforces 500 blocks for in-budget output, with a property
  that fills the budget with block-heavy lines.
- Public receive tests cross the message, click and command deadlines.
A line of U+00A0 or other non-ASCII whitespace is paragraph text to
CommonMark, but trim() made the renderer treat it as a blank line. That
reset the emphasis and container counts and allowed a new table after
it. One isBlank predicate now governs paragraph, setext and table state.

Adds the review's two inputs to the parser-backed corpus and non-ASCII
whitespace (U+00A0, U+3000, \v, \f) to the hostile generator.
Refuse a reply button whose wire id is over 256 UTF-8 bytes before the call, add an optional messagingAccountId sent as messaging_account_id, raise the webhook deadline to 10 seconds, and record what the live checks covered and what is still unchecked.
Live checks 1 to 5, 7, 10, 11 and 13 to 16 ran against the production
Bot API. Telegram's rich Markdown differs from CommonMark in ways the GFM
oracle could not see:

- It closes a link at an escaped `]` and ignores `\<`, `\:` and other
  escapes, so `[x](tg://...)`, a consumer's `[x\](tg://...)` and
  `\<b>` stayed live. Refused links now lose their `(`, refused
  definitions their opening `[`, and unhonored escapes become numeric
  character references. The GFM oracle now flags unhonored escapes.
- It reads destinations verbatim, so escaping them corrupted every link
  with a query string and turned allowed tg://user mentions into plain
  links. Kept destinations are sent verbatim, titles dropped; a link is
  kept only with its opener on the line, a definition only at the top
  level after a blank line or another definition.
- It reads definitions past other brackets and with leading space.
- It opens emphasis between spaces (`2 * 3 * 4`); such runs are escaped.
- It refuses a paragraph past about 4,387 inline nodes and about 773
  references to one footnote, which in-budget code spans and footnotes
  could reach. Both are now capped.
- Its rich message errors (RICH_MESSAGE_*) matched no refinement and all
  mapped to telegram_400. They are now mapped.

Adds an opt-in live conformance test and records the results, the
privacy-mode mention rule and in-order redelivery in the README.
Clicks carry Telegram's current keyboard, which caps at 100 buttons and
8 per row without an error. Ephemeral commands arrive with message_id 0,
ephemeral_message_id and receiver_user and take only the command path.
Private answers are refused and nothing is posted. The bystander half of
check 9 and forged click data were not tried.
The base live checks passed on production after the renderer fixes, so
@effect/chat-telegram is no longer private. It joins the fixed release
group and the effect-chat changeset, and is listed in the root README.
Files, buttons and commands stay behind the unverified options.
A kept link's destination is sent verbatim, which is inert only if it is
read as a link. A nested label, a full or collapsed reference before it
(`[a][b](…)`, `[a][](…)`) or a footnote reference can each leave the
outer brackets as text, and the destination as Markdown. A destination
is now kept only when its label holds no other bracket and no `]` comes
right before it.

- Each `[` that could open a link or reference counts toward
  maxInlineNodes, so shortcut and full references are capped too.
- A destination with unbalanced parentheses is no link to CommonMark,
  so it is no longer kept.
- A `[` that starts a line and is not closed on it is escaped, since a
  definition's label may end on a later line.
- The GFM oracle reads escapes in one pass, so `\!\<b>` is caught,
  and counts inline nodes per paragraph for assertInert.
- The live suite runs only when all three variables are set, as the
  README says. The README no longer claims cross-chat stalling, which
  was not tried, and lists the polling side of check 7 as not run.
Rich-message media: up to 50 files per message (51 is refused with 413),
names and MIME types kept except some characters outside Latin-1, and an
edit drops the media. Downloads through the adapter are byte for byte.
Reactions carry the user's whole set before and after and normalise to
no event.
As a user client, clicks with data not on the message's current
keyboard (forged, tampered, from another message, or from a keyboard an
edit replaced) are refused by Telegram with DATA_INVALID. Only genuine
clicks reach the adapter, whose own check is a second layer.
… are unambiguous

A line whose first [ meets a ]: is now decided up front from the raw
line: kept as a definition only at the top level after a blank line,
with a plain label (no bracket, code span, autolink or escaped ]), not
blank, not footnote-like, at most 999 characters, and nothing after an
allowed destination but a title. Otherwise its [ is escaped before the
line is read, so a raw destination never follows a label that is text.
Links and definitions share one destination scanner.

Also: autolinks refuse control characters; a footnote marker behind a
tab or four spaces is not a footnote; a delimiter row that is a list
item, or a lone pipe, heads no table; code spans split at pipes on lines
GFM may still read as table rows.
…'s nesting

A definition's label is now measured as the renderer will send it: an
escape counts as up to seven characters and each of $ = | * _ ~ as two,
and the bound must stay within CommonMark's 999. A label that grows past
it as it is escaped is refused up front, so its raw destination is not
copied behind text.

The destination scanner shared by links and definitions refuses
parentheses nested more than three deep, the least CommonMark lets a
parser support. GFM refuses a link past 32, which left its raw tail as
Markdown.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant